Copyright ã1995 by NeXT Computer, Inc.  All Rights Reserved.

NS_DEV_DOCFOR:objc_class:Responder;,Responder

Inherits From:	Object

Declared In:	appkit/Responder.h

Class Description

Responder is an abstract class that forms the basis of command and event processing in the Application Kit.  Most Kit classes inherit from Responder.  When a Responder object receives an event or action message that it can't respond toÐthat it doesn't have a method forÐthe message is sent to its next responder.  For a View, the next responder is usually its superview; the content view's next responder is the Window.  Each Window, therefore, has its own responder chain.  Messages are passed up the chain until they reach an object that can respond.

Action messages and keyboard event messages are sent first to the first responder, the object that displays the current selection and is expected to handle most user actions within a window.  Each Window object has its own first responder.  Messages the first responder can't handle work their way up the responder chain.

This class defines the methods and instance variable that pass event and action messages along the responder chain.

Instance Variables

id	nextResponder;

nextResponder 	The object that will be sent event messages and action messages that the Responder can't handle.

Method Types

Freeing an instance	- free

Setting the next responder	- setNextResponder:
- nextResponder

Determining the first responder	- acceptsFirstResponder
- becomeFirstResponder
- resignFirstResponder

Aiding event processing	- performKeyEquivalent: 
- tryToPerform:with:

Forwarding event messages	- mouseDown: 
- rightMouseDown: 
- mouseDragged: 
- rightMouseDragged: 
- mouseUp: 
- rightMouseUp:
- mouseMoved: 
- mouseEntered: 
- mouseExited: 
- keyDown: 
- keyUp: 
- flagsChanged: 
- noResponderFor: 

Services menu support	- validRequestorForSendType:andReturnType:

Help menu support	- helpRequested:

Archiving	- read: 
- write:

Instance Methods

NS_DEV_DOCFOR:objc_method:[Responder-acceptsFirstResponder];,acceptsFirstResponder

- (BOOL)acceptsFirstResponder

Returns NO to indicate that, by default, a Responder doesn't agree to become the first responder.

Before making any object the first responder, the Application Kit gives it an opportunity to refuse by sending it an acceptsFirstResponder message.  Objects that can display a selection should override this default to return YES.  Objects that respond with this default version of the method will receive mouse event messages, but no others.

See also:  - makeFirstResponder: (Window)

NS_DEV_DOCFOR:objc_method:[Responder-becomeFirstResponder];,becomeFirstResponder

- becomeFirstResponder

Notifies the receiver that it has just become the first responder for its Window.  This default version of the method simply returns self.  Responder subclasses can implement their own versions to take whatever action may be necessary, such as highlighting the selection.

By returning self, the receiver accepts being made the first responder.  A Responder can refuse to become the first responder by returning nil.

becomeFirstResponder messages are initiated by the Window object (through its makeFirstResponder: method) in response to mouse-down events.

See also:  - resignFirstResponder, - makeFirstResponder: (Window)

NS_DEV_DOCFOR:objc_method:[Responder-flagsChanged:];,flagsChanged:

- flagsChanged:(NXEvent *)theEvent

Passes the flagsChanged: event message to the receiver's next responder.

NS_DEV_DOCFOR:objc_method:[Responder-free];,free

- free

Frees the space used by a Responder instance and removes it from the hash table used to locate help.  Returns self.

NS_DEV_DOCFOR:objc_method:[Responder-helpRequested:];,helpRequested:

- helpRequested:(NXEvent *)eventPtr

Invoked by a Window instance when the user has clicked for help. The Window instance sends this message to the first responder.  The receiver shows its help panel if it has one, and if not forwards the message to the next responder. If there is no next responder to respond, the method executes NXBeep(). Your application should never invoke this method directly.  Returns self.

NS_DEV_DOCFOR:objc_method:[Responder-keyDown:];,keyDown:

- keyDown:(NXEvent *)theEvent

Passes the keyDown: event message to the receiver's next responder.

NS_DEV_DOCFOR:objc_method:[Responder-keyUp:];,keyUp:

- keyUp:(NXEvent *)theEvent

Passes the keyUp: event message to the receiver's next responder.

NS_DEV_DOCFOR:objc_method:[Responder-mouseDown:];,mouseDown:

- mouseDown:(NXEvent *)theEvent

Passes the mouseDown: event message to the receiver's next responder.

NS_DEV_DOCFOR:objc_method:[Responder-mouseDragged:];,mouseDragged:

- mouseDragged:(NXEvent *)theEvent

Passes the mouseDragged: event message to the receiver's next responder.

NS_DEV_DOCFOR:objc_method:[Responder-mouseEntered:];,mouseEntered:

- mouseEntered:(NXEvent *)theEvent

Passes the mouseEntered: event message to the receiver's next responder.

NS_DEV_DOCFOR:objc_method:[Responder-mouseExited:];,mouseExited:

- mouseExited:(NXEvent *)theEvent

Passes the mouseExited: event message to the receiver's next responder.

NS_DEV_DOCFOR:objc_method:[Responder-mouseMoved:];,mouseMoved:

- mouseMoved:(NXEvent *)theEvent

Passes the mouseMoved: event message to the receiver's next responder.

NS_DEV_DOCFOR:objc_method:[Responder-mouseUp:];,mouseUp:

- mouseUp:(NXEvent *)theEvent

Passes the mouseUp: event message to the receiver's next responder.

NS_DEV_DOCFOR:objc_method:[Responder-nextResponder];,nextResponder

- nextResponder

Returns the receiver's next responder.

See also:  - setNextResponder:

NS_DEV_DOCFOR:objc_method:[Responder-noResponderFor:];,noResponderFor:

- noResponderFor:(const char *)eventType

Responds to an event message that has reached the end of the responder chain without finding an object that can respond.  When the event is a key down, noResponderFor: generates a beep.

NS_DEV_DOCFOR:objc_method:[Responder-performKeyEquivalent:];,performKeyEquivalent:

- (BOOL)performKeyEquivalent:(NXEvent *)theEvent

Returns NO to indicate that, by default, the Responder doesn't have a key equivalent and can't respond to key-down events as keyboard alternatives.

The Responder class implements this method so that any object that inherits from it can be asked to respond to a performKeyEquivalent: message.  Subclasses that define objects with key equivalents must implement their own versions of performKeyEquivalent:.  If the key in theEvent matches the receiver's key equivalent, it should respond to the event and return YES.

See also:  - performKeyEquivalent: (View and Button)

NS_DEV_DOCFOR:objc_method:[Responder-read:];,read:

- read:(NXTypedStream *)stream

Reads the Responder from the typed stream stream.  Returns self.

See also:  - write:

NS_DEV_DOCFOR:objc_method:[Responder-resignFirstResponder];,resignFirstResponder

- resignFirstResponder

Notifies the receiver that it has been asked to relinquish its status as first responder for its Window.  This default version of the method simply returns self.  Responder subclasses can implement their own versions to take whatever action may be necessary, such as unhighlighting the selection.

By returning self, the receiver accepts the change.  By returning nil, the receiver refuses to agree to the change, and remains the first responder.

A resignFirstResponder message is sent to the current first responder (through Window's makeFirstResponder: method) when another object is about to be made the new first responder.

See also:  - becomeFirstResponder, - makeFirstResponder: (Window)

NS_DEV_DOCFOR:objc_method:[Responder-rightMouseDown:];,rightMouseDown:

- rightMouseDown:(NXEvent *)theEvent

Passes the rightMouseDown: event message to the receiver's next responder.

NS_DEV_DOCFOR:objc_method:[Responder-rightMouseDragged:];,rightMouseDragged:

- rightMouseDragged:(NXEvent *)theEvent

Passes the rightMouseDragged: event message to the receiver's next responder.

NS_DEV_DOCFOR:objc_method:[Responder-rightMouseUp:];,rightMouseUp:

- rightMouseUp:(NXEvent *)theEvent

Passes the rightMouseUp: event message to the receiver's next responder.

NS_DEV_DOCFOR:objc_method:[Responder-setNextResponder:];,setNextResponder:

- setNextResponder:aResponder

Makes aResponder the receiver's next responder.

See also:  - nextResponder

NS_DEV_DOCFOR:objc_method:[Responder-tryToPerform:with:];,tryToPerform:with:

- (BOOL)tryToPerform:(SEL)anAction with:anObject

Aids in dispatching action messages.  This method checks to see whether the receiving object can respond to the method selector specified by anAction.  If it can, the message is sent with anObject as an argument.  Typically, anObject is the initiator of the action message.

If the receiver can't respond, tryToPerform:with: checks to see whether the receiving object's next responder can.  It continues to follow next responder links up the responder chain until it finds an object that it can send the action message to, or the chain is exhausted.

Even if the receiver can respond to anAction messages, it can ªrefuseº them by having its implementation of the anAction method return nil.  In this case, the message is passed on to the next responder in the chain.

If successful in finding a receiver that doesn't refuse the message, tryToPerform: returns YES.  Otherwise, it returns NO.

This method is used (indirectly, through the sendAction:to:from: method) to dispatch action messages from Control objects.  You'd rarely have reason to use it yourself.

See also:  - sendAction:to:from: (Application)

NS_DEV_DOCFOR:objc_method:[Responder-validRequestorForSendType:andReturnType:];,validRequestorForSendType:andReturnType:

- validRequestorForSendType:(NXAtom)typeSent
andReturnType:(NXAtom)typeReturned

Implemented by subclasses to determine what services are available at any given time.  In order to keep the Services menu current, the Application object sends validRequestorForSendType:andReturnType: messages to the first responder with the send and return types for each service method of every service provider.  Thus, a Responder may receive this message many times per event.  If the receiving object can place data of type typeSent on the pasteboard and receive data of type typeReturned back, it should return self; otherwise it should return nil.  The Application object checks the return value to determine whether to enable or disable commands in the Services menu.

Responder's implementation of this method simply forwards the message to the next responder, so by default this method returns nil.  Like untargeted action messages, validRequestorForSendType:andReturnType: messages are passed up the responder chain to the Window, then to the Window's delegate, and finally to the Application object and its delegate, until an object returns self rather than nil.

typeSent and typeReturned are pasteboard types.  They're NXAtoms, so you can compare them to the types your application can send and receive by comparing pointers rather than comparing strings.  Since this method will be invoked frequently, it must be as efficient as possible.

Either typeSent or typeReturned may be NULL.  If typeSent is NULL, the service doesn't require data from the requesting application.  If typeReturned is NULL, the service doesn't return data to the requesting application.

When the user chooses a menu item for a service, a writeSelectionToPasteboard:types: message is sent to the Responder (if typeSent was not NULL).  The Responder writes the requested data to the pasteboard and a remote message is sent to the service.  If the service's typeReturned is not NULL, it places return data on the pasteboard, and the Responder receives a readSelectionFromPasteboard: message.

The following example demonstrates an implementation of the validRequestorForSendType:andReturnType: method for an object that can send and receive ASCII text.  Pseudocode is in italics.

- validRequestorForSendType:(NXAtom)typeSent
                        andReturnType:(NXAtom)typeReturned
{
    /*
     * First, check to make sure that the types are ones
     * that we can handle.
     */
    if ( (typeSent == NXAsciiPboardType || typeSent == NULL) &&
        (typeReturned == NXAsciiPboardType || typeReturned == NULL) )
    {
        /*
         * If so, return self if we can give the service
         * what it wants and accept what it gives back.
         */
        if ( ((there is a selection) || typeSent == NULL) &&
             ((the text is editable) || typeReturned == NULL) )
        {
            return self;
        }
    }
    /*
     * Otherwise, return the default.
     */
    return [super validRequestorForSendType:typeSent
                                    andReturnType:typeReturned];
}

See also:  - registerServicesMenuSendTypes:andReturnTypes: (Application), - writeSelectionToPasteboard:types: (Application), - readSelectionFromPasteboard: (Application)

NS_DEV_DOCFOR:objc_method:[Responder-write:];,write:

- write:(NXTypedStream *)stream

Writes the receiving Responder to the typed stream stream.  The next responder is not explicitly written.  Returns self.

See also:  - read: